package com.github.xtranslation.core.threadpool;

import io.vavr.control.Option;

import java.util.concurrent.ThreadPoolExecutor;

/**
 * XTranslation线程池管理器接口
 * <p>
 * 允许使用方自定义线程池实现,支持动态线程池等高级功能。
 *
 * <h3>设计哲学</h3>
 * <p>
 * 本接口采用基于代码而非配置(yml等)文件的设计理念,主要基于以下考量：
 * <ul>
 *   <li>配置文件方式相对静态,无法满足动态线程池等高级场景需求</li>
 *   <li>使用方可通过实现此接口,完全掌控线程池的行为和生命周期</li>
 *   <li>支持从配置中心动态获取参数并实时调整线程池配置</li>
 * </ul>
 *
 * <h3>解决的核心痛点</h3>
 * <ol>
 *   <li><strong>参数调优困难</strong>：开发人员难以准确评估线程池核心参数的最佳设置</li>
 *   <li><strong>动态调整不便</strong>：基于配置文件的方式需要重启服务才能生效</li>
 *   <li><strong>运行状态不透明</strong>：传统线程池对开发者而言是黑盒,缺乏实时监控能力</li>
 * </ol>
 *
 * <h3>遵循的设计原则</h3>
 * <ul>
 *   <li><strong>开闭原则</strong>：对扩展开放,对修改关闭</li>
 *   <li><strong>依赖倒置原则</strong>：依赖抽象接口而非具体实现</li>
 *   <li><strong>最小惊讶原则</strong>：保持向后兼容性,降低使用成本</li>
 * </ul>
 *
 * @author zhangxiaoxiang
 * @see ThreadPoolExecutor
 * @since 2023/9/2
 */
public interface XTranslationThreadPoolManager {

    /**
     * 获取线程池执行器
     * <p>
     * 使用方可以在此方法中返回自定义的线程池实现,例如：
     * <ul>
     *   <li>基于配置中心动态调整参数的线程池</li>
     *   <li>支持监控和告警的线程池</li>
     *   <li>支持任务优先级的线程池</li>
     *   <li>其他自定义功能的线程池</li>
     * </ul>
     *
     * @return 线程池执行器实例
     */
    ThreadPoolExecutor getExecutor();

    /**
     * 销毁线程池
     * <p>
     * 当框架关闭时会调用此方法,使用方可以在此方法中执行资源清理工作。
     * 例如优雅关闭线程池、记录统计信息等。
     *
     */
    default void destroy() {
        Option.of(getExecutor())
                .filter(executor -> !executor.isShutdown())
                .forEach(ThreadPoolExecutor::shutdown);
    }
}
